chore: prepare MCPAudit 2.5.0 release candidate by saagpatel · Pull Request #171 · saagpatel/MCPAudit

saagpatel · 2026-07-19T19:13:10Z

Summary

Prepare MCPAudit 2.5.0 as a reviewable, intentionally non-publishable release candidate. The candidate packages Proof Before Action and the security repairs already landed on main, aligns package/server/changelog metadata, and separates tag creation from PyPI publication with an exact tag/commit-bound manual workflow.

Changes

Set the candidate version to 2.5.0 across pyproject.toml, server.json, uv.lock, CLI tests, and the changelog.
Add candidate release notes, Proof Before Action security boundaries, compatibility/rollback guidance, and a machine-readable docs/release-state.json.
Keep public Action/pre-commit examples on existing tag v2.4.0 while candidate state is non-publishable.
Keep server.json registry metadata on published 2.4.0 until the separately reviewed release-state transition, so registry clients never receive an unavailable package version.
Make publishable state require finalized published/previous versions, dated changelog and comparison links, versioned release notes, and exact wheel/sdist entry points; candidate smoke installs now use the built artifacts, not unversioned PyPI.
Expose proof-before-action --version consistently with the sibling commands.
Replace automatic v* tag publication with a manual workflow that requires live non-bypassable independent environment review, an exact tag, an exact 40-character landed commit, full quality gate, clean package provenance, retained artifacts, and hash readback before the OIDC-enabled publish job.
Add scripts/verify_release.py and regression coverage for metadata, candidate fail-closed behavior, publication triggers, OIDC authority placement, public-version examples, and the newly used pinned artifact actions.

Checklist

Canonical verifier passes (uv run pytest, uv run ruff check, uv run mypy .)
Security implications considered — release authority, OIDC timing, dependency floor, evidence authority, rollback, and public trust claims are described below.
CHANGELOG.md updated under [Unreleased]
New or changed behavior is documented (README, docstrings, or both)

Security implications

The candidate retains mcp>=1.28.1 and immutable external Action pins. A security-focused diff review found one Medium/P2 supply-chain authorization gap in the previous workflow: pushing a v* tag automatically obtained PyPI publication authority despite the documented separate-approval boundary. This PR removes the tag trigger and makes candidate state mechanically non-publishable.

Unknown, stale, masked, unmatched, incomplete, unobservable, dirty, or authority-unverified Proof Before Action evidence remains non-authoritative. The Docker observer is not a general sandbox guarantee and intentionally accepts only bounded UTF-8 repository inputs plus explicitly named synthetic SQLite fixtures.

Residual release risks are preserved, not closed cosmetically:

the repository has one eligible human collaborator, so genuine independent human approval is unavailable;
the live pypi environment currently has no required reviewer and permits administrator bypass;
continuous fuzzing, OpenSSF Best Practices enrollment, and two independent redacted field reports are absent.

Those limitations do not block merging an intentionally non-publishable candidate, but public release remains NO-GO until the exact candidate is separately authorized, the environment has independent reviewer protection, and the human-review risk is satisfied or explicitly accepted.

Test plan

uv run pytest: 1022 passed
uv run pytest tests/test_proof_before_action.py -q: 125 passed
connector/server/release/distribution/integrity/package-policy set: 103 passed
Ruff, formatting, strict mypy, uv lock --check, and git diff --check: pass
validation corpus: 117/118, 99.2% recall; all category gates pass
Gitleaks whole-tree scan: no leaks
Clean exact commit build: wheel and sdist metadata, mcp>=1.28.1, clean producer provenance, content hygiene, embedded README, and three entry points verified
Isolated wheel and sdist installs: mcp-audit, mcp-audits, and proof-before-action all report 2.5.0
Installed Proof Before Action flow: declaration → Docker observation → comparison → trust manifest → capsule → anchored verification passed with exact producer/subject commits and independently supplied root; wrong root/image/commits, tampered HTML, malformed input, and absent authority root produced the documented fail-closed results
Docker cleanup: zero task-owned containers and staging images after positive and blocked paths

Exact candidate artifacts from commit 6cc0cafbc9c081bfeb876185f3d6aa7e7461db9e:

wheel SHA-256: 5216112e4ecd17af80e10f716cc7bad1a6ae5d317f0ee53c97303172e42c5485
sdist SHA-256: 22515475987c8987b61e9b6d4c8e104eaa6e49c01989341f522e8dd913518083

A fresh exact-head Codex Security scan is requested for 6cc0cafbc9c081bfeb876185f3d6aa7e7461db9e and remains required before merge; an earlier working-tree scan was correctly failed after remediation changed its snapshot.

Compatibility and rollback

2.5.0 is an additive minor release for Python 3.11–3.13 and keeps the 2.x report/SARIF compatibility policy. Existing consumers must allow mcp>=1.28.1.

Prefer reverting consuming configuration while retaining 2.5.0. If an emergency package rollback to 2.4.0 is unavoidable, also constrain mcp>=1.28.1 and read back both resolved versions; the existing v2.4.0 Action/pre-commit tag is not represented as a security-safe rollback.

Publication boundary

This PR does not authorize or perform a tag, GitHub Release, PyPI publication, deployment, or external registry/trust-source change. Finalizing release state, creating the tag, and manually dispatching publication require separate exact authorization after the landed commit and live protection state are reverified.

Related issues

N/A

github-actions · 2026-07-19T19:13:25Z

Agent Permission Diff

Base: 3850b11136190a3abcee01ec923bddd7b7eb48be
Head: 6cc0cafbc9c081bfeb876185f3d6aa7e7461db9e
Findings: 1
Gate findings: 1
Acknowledged findings: 0
Permission changes: 18
Gate: observe in observe mode
Fail on: critical
Exit code: 0

Gate Decision

Max severity high is recorded but observe mode never fails.

Findings

HIGH APD002: OIDC token permission added

A workflow gained id-token: write, enabling cloud/provider identity federation.

Reviewer decision: Confirm this is paired with a protected, intended deployment path.

Evidence:

permissions.id-token: write

Permission Changes

added actions cloud_deploy curl --fail --location --silent --show-error \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer $GH_TOKEN... in .github/workflows/publish.yml
added actions cloud_deploy git fetch --force --tags origin main uv run python scripts/verify_release.py \ --tag "$RELEASE_TAG" \ --commit "$RELEASE_COMMIT" \ --envi... in .github/workflows/publish.yml
added actions cloud_deploy uv run python scripts/verify_release.py \ --tag "$RELEASE_TAG" \ --commit "$RELEASE_COMMIT" \ --environment-json "$RUNNER_TEMP/pypi-envir... in .github/workflows/publish.yml
added actions runner ubuntu-latest in .github/workflows/publish.yml
added actions cloud_deploy curl --fail --location --silent --show-error \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer $GH_TOKEN... in .github/workflows/publish.yml
added actions cloud_deploy pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 in .github/workflows/publish.yml
added actions deployment_environment pypi in .github/workflows/publish.yml
added actions runner ubuntu-latest in .github/workflows/publish.yml
added actions token_permission actions:read in .github/workflows/publish.yml
added actions token_permission contents:read in .github/workflows/publish.yml
added actions token_permission id-token:write in .github/workflows/publish.yml
added actions runner ubuntu-latest in .github/workflows/publish.yml
added actions token_permission actions:read in .github/workflows/publish.yml
removed actions cloud_deploy pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 in .github/workflows/publish.yml
removed actions deployment_environment pypi in .github/workflows/publish.yml
removed actions runner ubuntu-latest in .github/workflows/publish.yml
removed actions token_permission contents:read in .github/workflows/publish.yml
removed actions token_permission id-token:write in .github/workflows/publish.yml

saagpatel · 2026-07-19T19:13:45Z

@codex review

Use light reasoning. Review exact head f7d9e11c8da84a589594a34673e9fe760b8754d9, findings first and severity first. Focus on the candidate-versus-published version boundary, the removal of tag-triggered publication, exact tag/commit/main binding, candidate fail-closed behavior, OIDC authority placement, retained artifact/hash verification, immutable Action policy, rollback safety, and any misleading Proof Before Action or release claim. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7d9e11c8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T19:25:47Z

Agent Permission Diff disposition for exact head 37aa80f88767e16ed84dcfdb082f1aa8368710ce:

APD002 is an expected relocation, not a net-new repository capability: id-token: write, the pypi environment, and the pinned PyPI publisher already existed on the base publish job.
This candidate narrows that authority to a dedicated publish job after manual dispatch, exact tag/commit/main binding, candidate-state refusal, full quality gates, clean artifact provenance, retained-artifact transfer, and SHA-256 readback.
The live pypi environment still has no required reviewer and permits administrator bypass. That is not treated as protected or green: public release remains NO-GO, and the checklist requires live independent-reviewer protection before any separately authorized dispatch.
Candidate merge does not tag, dispatch, request OIDC, or publish; docs/release-state.json keeps the landed candidate mechanically non-publishable.

saagpatel · 2026-07-19T19:25:55Z

@codex review

Use light reasoning. Re-review exact repaired head 37aa80f88767e16ed84dcfdb082f1aa8368710ce, findings first and severity first. Confirm the prior P1 registry finding and both independent P2 package-gate findings are closed: candidate server.json must stay on public 2.4.0; publishable state must require finalized public/changelog/link/release-note metadata; the verifier must bind all three wheel/sdist entry points; and candidate install smoke must use exact built artifacts. Also recheck manual publication, tag/commit/main binding, OIDC placement, and any misleading safety or release claim. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37aa80f887

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T19:59:49Z

@codex review

Use light reasoning. Re-review exact repaired head 65fe5519afccb3ab1e2013b1a6bb1aa20c577f84, findings first and severity first. Confirm the prior P1 registry finding, both package-gate P2s, and the checklist-order P2 are closed. In particular: candidate server.json stays on public 2.4.0; publishable state requires finalized public/changelog/link/release-note metadata; all three wheel/sdist entry points are bound; and the documented exact-candidate sequence verifies the built artifacts with the exact clean commit before installing either one. Recheck manual publication, tag/commit/main binding, OIDC placement, rollback safety, and misleading safety or release claims. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 65fe5519af

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T20:09:34Z

@codex review

Use light reasoning. Review exact repaired head fccd80b462aceae0d309f33676e58f3091e50b3b, findings first and severity first. Confirm all prior P1/P2 findings are closed. Focus especially on the removal of the copyable approval input, fail-closed live pypi environment readback (required reviewer, self-review prevention, admin-bypass disabled) both before build authorization and inside the OIDC publish job, finalized release-note status enforcement, exact tag/commit/main/artifact binding, and candidate non-publishability. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fccd80b462

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T20:26:32Z

@codex review

Use light reasoning. Final re-review of exact head 2db2cada388e4897927e80c2d7a48081302662ee, findings first and severity first. Confirm all prior findings are closed, especially that release notes require exactly one non-conflicting status marker and exactly one matching GO/NO-GO publication decision. Recheck the live non-bypassable independent PyPI-environment gate, candidate non-publishability, tag/commit/main/artifact binding, and misleading release or safety claims. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2db2cada38

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T20:43:19Z

@codex review

Use light reasoning. Final exact-head review of e0cb2777ce41be416f9f664c744cf5c60ab7dc3b, findings first and severity first. Confirm all previous findings are closed, especially that manual-dispatch YAML is bound to refs/heads/main on both build and OIDC publish jobs. Recheck the live independent environment gate, exact tag/commit/main/artifact binding, singleton release-note state/decision contract, and candidate non-publishability. Do not treat unavailable review as clean.

chatgpt-codex-connector · 2026-07-19T20:45:13Z

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: e0cb2777ce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T20:59:10Z

@codex review

Light reasoning only. Review exact head e0cb2777ce41be416f9f664c744cf5c60ab7dc3b. Findings first. This delta binds both manual publish jobs to refs/heads/main; verify that closes the prior P1 without weakening the live independent-environment, release-state, tag/commit/artifact, or candidate NO-GO gates. Do not treat unavailable review as clean.

chatgpt-codex-connector · 2026-07-19T21:00:28Z

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: e0cb2777ce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T21:01:26Z

@codex review

Use light reasoning. Review exact head aa0144d22b86b4c58f345f2460cf330beb9af8a5, findings first. Confirm the prior non-main-dispatch P1 is closed without a green no-op: the always-running validation job must fail unless the selected workflow definition is refs/heads/main, and build must depend on it. Recheck all earlier live environment, OIDC, release-note, exact tag/commit/artifact, and candidate NO-GO gates. Do not treat unavailable review as clean.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aa0144d22b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T21:17:54Z

@codex review

Use light reasoning. Review exact head 6cc0cafbc9c081bfeb876185f3d6aa7e7461db9e, findings first. Confirm all previous findings are closed, especially the authenticated live environment read: minimum actions: read, masked github.token passed via environment, both pre-build and OIDC-job requests authenticated, and no secret interpolation/logging. Recheck loud non-main failure and all prior publication/candidate gates. Do not treat unavailable review as clean.

chatgpt-codex-connector · 2026-07-19T21:20:09Z

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 6cc0cafbc9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

saagpatel · 2026-07-19T21:32:55Z

Exact-head closeout for 6cc0cafbc9c081bfeb876185f3d6aa7e7461db9e:

All CI/check runs are green on this SHA.
All seven prior Codex review findings are repaired and their threads resolved. The final authentication delta has an independent exact-head review with no findings; the requested final Codex re-review has not returned a receipt and is not treated as clean.
Full local gate: 1022 passed; Ruff, formatting, mypy, lock, diff, and Gitleaks pass.
Exact artifacts reproduced twice: wheel 5216112e4ecd17af80e10f716cc7bad1a6ae5d317f0ee53c97303172e42c5485; sdist 22515475987c8987b61e9b6d4c8e104eaa6e49c01989341f522e8dd913518083.
Installed Proof Before Action exact-head lane is green, including anchored verification and fail-closed wrong-root behavior.
Public release remains mechanically NO-GO: live pypi environment has no reviewer rule and permits admin bypass; workflow now fails on that state.
Candidate merge remains blocked on the required independent GitHub approval (repository has one collaborator) and an unstarted exact-head native Codex Security workspace. No branch-protection bypass, tag, release, PyPI publication, dispatch, or registry change was performed.

saagpatel added 2 commits July 19, 2026 11:52

chore: prepare 2.5.0 release candidate

e739289

fix: verify untagged candidate artifacts

f7d9e11

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread server.json

fix: close release candidate gate gaps

37aa80f

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread docs/RELEASE-CHECKLIST.md

fix verify candidate artifacts before install

65fe551

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread .github/workflows/publish.yml Outdated

Comment thread scripts/verify_release.py Outdated

fix require independent publication approval

fccd80b

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread scripts/verify_release.py Outdated

fix reject conflicting release status

2db2cad

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread .github/workflows/publish.yml

fix bind publish dispatch to main

e0cb277

fix fail non-main publish dispatch

aa0144d

chatgpt-codex-connector Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread .github/workflows/publish.yml

fix authenticate environment protection readback

6cc0caf

saagpatel merged commit 7522a91 into main Jul 19, 2026
7 checks passed

saagpatel deleted the agent/release-2.5.0 branch July 19, 2026 21:40

saagpatel restored the agent/release-2.5.0 branch August 5, 2026 05:47

Conversation

saagpatel commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Checklist

Security implications

Test plan

Compatibility and rollback

Publication boundary

Related issues

Uh oh!

github-actions Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Agent Permission Diff

Gate Decision

Findings

HIGH APD002: OIDC token permission added

Permission Changes

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 19, 2026

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 19, 2026

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 19, 2026

Uh oh!

saagpatel commented Jul 19, 2026

Uh oh!

Uh oh!

saagpatel commented Jul 19, 2026 •

edited

Loading

github-actions Bot commented Jul 19, 2026 •

edited

Loading